Chuyển tới nội dung chính

Ký Request API Seller (multipart/form-data)

API Tạo Seller và Cập Nhật Seller gửi dữ liệu dạng multipart/form-data (vì có kèm upload file trong trường files), khác với phần lớn API khác của Baokim gửi application/json. Vì vậy cách tính chữ ký (Signature) cho 2 API này khác với hướng dẫn chung ở trang Giới thiệu API Baokim — trang này bổ sung riêng phần khác biệt đó.

Trước khi đọc tiếp, đối tác cần nắm rõ phần 6. Chi tiết định dạng Signature và 7. Hướng dẫn bảo mật chung ở trang Giới thiệu — các quy định về keyVersion, algorithm, cặp khóa RSA/ED25519, header Signature vẫn áp dụng nguyên vẹn, chỉ riêng nội dung được đem đi ký (plaintext) là khác.

1. Sự khác biệt so với API JSON thông thường​

API JSON thông thườngAPI Tạo/Cập nhật Seller
Content-Typeapplication/jsonmultipart/form-data
Dữ liệu ký (plaintext)Nguyên văn raw JSON body của requestJSON được dựng lại từ toàn bộ field form (xem mục 2)

Baokim xác định request là "kiểu multipart" dựa vào header Content-Type. Nếu header này chứa multipart/form-data hoặc application/x-www-form-urlencoded, hệ thống sẽ không dùng raw body để verify chữ ký (vì raw body của multipart chứa cả boundary, header từng phần, dữ liệu nhị phân của file — không thể ký/so khớp trực tiếp như JSON). Thay vào đó, hệ thống dựng lại 1 object JSON từ toàn bộ field đã được parse, rồi mới đem đi verify.

2. Cách dựng plaintext để ký​

Plaintext = JSON của toàn bộ field trong form (kể cả trường files), encode bằng flag JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE.

plaintext = json_encode(<toàn bộ field form đã parse>, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)

Lưu ý quan trọng khi dựng lại object này ở phía đối tác:

  1. Các field text/array bình thường (request_id, request_time, merchant_code, seller_id, platform, ...): đưa nguyên giá trị đã gửi vào object, giữ đúng kiểu dữ liệu (string/array) như đã khai ở bảng Request của từng API.

  2. Field files — đây là điểm dễ sai nhất: nội dung nhị phân của file không được đưa vào plaintext. Ở phía server, mỗi phần tử file trong mảng files là 1 object file-handle nội bộ, không có thuộc tính public nào lộ ra ngoài — nên khi json_encode() toàn bộ payload, mỗi phần tử file sẽ luôn được serialize thành object rỗng {}, bất kể tên file/nội dung file thực tế là gì. Khi đối tác tự dựng lại plaintext để ký, phải thay giá trị của khoá file bằng {} (object rỗng), không phải tên file, không phải nội dung file, không phải base64 của file.

    Ví dụ minh hoạ (2 phần tử files, type khác nhau):

    "files": [
      { "type": "1", "file": {} },
      { "type": "2", "file": {} }
    ]

  3. Thứ tự field: đưa field vào object theo đúng thứ tự đã gửi trong multipart form (thường là thứ tự SDK/HTTP client của đối tác build request). Vì json_encode() giữ nguyên thứ tự key của mảng nguồn, sai thứ tự sẽ ra plaintext khác → verify chữ ký thất bại.

3. Ví dụ đầy đủ​

Với request mẫu ở trang Tạo Seller, plaintext cần ký là:

{
    "request_id": "MERCHANT12345678901234510281",
    "request_time": "2024-11-15 14:36:00",
    "merchant_code": "MERCHANT001",
    "sub_merchant_code": "MERCHANT001",
    "seller_id": "SELLER123456",
    "seller_name": "Nguyễn Văn A",
    "platform": [
        {
            "type": "2",
            "links": "https://shopee.vn/seller123",
            "platform_seller_id": "SHOPEE123456"
        }
    ],
    "files": [
        { "type": "1", "file": {} },
        { "type": "2", "file": {} }
    ],
    "representative_DOB": "1990-01-01",
    "representative_ID_number": "001099012345",
    "representative_name": "Nguyen Van A",
    "representative_nationality": "Vietnam",
    "representative_address": "1 Dai Co Viet Street, Hai Ba Trung District, Ha Noi",
    "seller_business_type": "2",
    "seller_business_registration_no": "0123456789",
    "seller_phone": "0912345678",
    "seller_email": "[email protected]",
    "seller_business_description": "Online retail store selling electronics",
    "seller_risk_level": "1",
    "gc_code": "5045",
    "mcc_code": "5399"
}

Sau khi có plaintext ở trên, các bước còn lại (ký bằng private key theo algorithm đã đăng ký, base64-encode chữ ký, gắn vào header Signature cùng keyVersion/algorithm) thực hiện đúng như hướng dẫn chung ở mục 6, trang Giới thiệu.

4. Lỗi thường gặp​

Triệu chứngNguyên nhân thường gặp
Chữ ký luôn sai dù dữ liệu gửi đúngĐưa nội dung/tên file thật vào plaintext thay vì {}
Chữ ký sai chỉ khi có > 1 fileThứ tự phần tử trong mảng files không khớp thứ tự đã gửi
Chữ ký đúng ở môi trường test JSON thuần nhưng sai khi submit multipart thậtNhầm dùng cách ký raw body (application/json) cho request multipart/form-data